!AngSound - Shared Angband sound resources - Release 4
~~~~~~~~~   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~   ~~~~~~~~~

Why a seperate resource?
````````````````````````
Well, that's because the alternative is to have a set of samples for each
version/variant of Angband you play.  Obviously it's far better to just have
one copy of "opendoor.wav" on your harddisc than four (or more) hidden away
inside !Angband, !Kamband, !Sangband, !Zangband, !Cthangbnd, etc.


Use
```
When !AngSound is first 'seen' by the Filer it will set up enough information
for the various games to know where the sounds are.  The PlayIt module
(which actually plays the sounds) won't be loaded at this point.

If you want to make sure that the sounds can be found, and that you have
PlayIt loaded ready, you can run (double-click on) !AngSound and that
will set everything up.

As of version 1.23 of my Angband front-ends you don't need to worry about
loading PlayIt since the game itself will ensure that PlayIt is loaded
when it's required as long as AngSound has been 'seen'.

When using a 'new' !Boot structure (eg. on RiscPCs or older machines that
have been updated from eg. the 4th Acorn User cover CD) it's probably
best to put !AngSound in !Boot.Resources so that it is automatically
seen when your machine boots.

You don't have to do this, however - anywhere is fine as long as AngSound is
seen before you try to use sound effects.

That's more or less all you need to know to use AngSound - most of the rest
of this file deals with the technical details you'll need to know if you
want to add explicit support for a variant that AngSound is unaware of
(this is unlikely to be needed) or meddle in some other way.  You may want
to skip ahead to the "Hints & Tips" section :)



PlayIt
``````
The games use Rick Hudson's versatile PlayIt module to actually play sounds.

PlayIt is freeware and used here under the terms of its licence
conditions.  My thanks to Rick Hudson for allowing PlayIt to be used
and distributed in this manner.  The current release of !AngSound contains
versions 1.36 and 1.39 of PlayIt.

NB: you can easily replace the version of PlayIt in !AngSound with a newer
one as and when required.  If you do so, it'd be a good idea to also
modify !AngSound.LoadPlayIt to ensure that the newer version is actually
loaded.

NB: I've had nasty trouble using PlayIt 1.39 on RISC OS 3.1 machines.
Typically this manifests as a "gruesome software bug" followed by a
successful "panic save".  For this reason, PlayIt 1.34 is supplied.

Sadly, PlayIt 1.34 seems to have some problems on RiscPCs that can result in
sounds 'clicking' at the end or being played as 'garbage'.

The latest version of PlayIt can be obtained from:
  http://home.clear.net.nz/pages/rickh/software/playit.html



Default sounds/configuration
````````````````````````````
Because you'll probably want to use some (if not all) of the same sounds
for several games, !AngSound is divided up internally into directories
for each game and a common 'Default' directory that is used if something
can't be found in the game-specific directory.

For example, if Zangband wants to play "hit.wav" then it will look for it
first in !AngSound.Zangband, then !AngSound.Default.

The same holds true for the configuration files (see later), ie. when a
game starts up it will try to use the sound/cfg file in its specific
directory, but if it doesn't exist it will use the one in the Default
directory.


Configuration files
```````````````````
When each game starts up (or when sound is (re)enabled from its
iconbar menu), it will attempt to read a file called "sound/cfg" from the
appropriate place in !AngSound.

Angband and its variants play sounds when certain events occur.  You may
specify more than one sound for each event, in which case one from the
list will be chosen at random.

The actual events that each game uses /can/ be different, however at the
moment the sound support in Angband itself is very crude and (as far as I
am aware) all the variants use the same event names.  Not all variants
actually play the sounds for all the events and some events don't result
in sounds at all.  This will (hopefully) change as the sound support in
Angband is improved.

The most important events are:

    EVENT:      PLAYED WHEN
    hit         you hit a monster
    miss        you miss a monster
    flee        a monster turns to "flee in terror"
    drop        something (including money) is dropped
    kill        a monster dies
    level       you 'go up' an experience level :)
    death       you die :(
    study       you gain (ie. learn) another spell
    teleport    you teleport, eg. Phase Door
    shoot       you fire a weapon
    quaff       you quaff a potion
    zap         you use a rod, wand, staff or artifact
    tpother     a monster teleports (or is teleported).
    hitwall     you bump into a wall
    eat         you eat something
    dig         you finish digging a tunnel
    opendoor    you open a door
    shutdoor    you close a door
    tplevel     you teleport to a different level (eg. Word of Recall)
    scroll      you read a scroll
    buy         you buy something
    sell        you sell something
    warn        a warning (eg. ** LOW HITPOINT WARNING **) is displayed.

(actually, there aren't many more events than that anyway).

The format of the file is the same as for the DOS versions of Angband.
Basically this boils down to a list of event names, each of which is
followed by an '=' character and then a list of sound file names.

You should only give each event once but you may specify as many sounds
for that event as you like (up to a 2000 or so character limit on the line
length).

Lines beginning with a '#' or white-space character will be skipped, as will
any line beginning with a '[' (this is for compatibility with sound/cfg
files from DOS versions which have a "[Sound]" label in the file).

When each sound filename is read, it will be RISCOSified, ie. dots will
be translated into slashes and vice versa.  Again, this is for compatibility
with DOS filenames.

Whitespace within a line is ignored.

Filenames will be truncated to 15 characters if they are longer than this.
This is unlikely to affect you unless you are using a filing system that
permits long filenames and actually using long filenames for the sound files.

eg. the line:

   teleport = teleport.wav tele1.wav zap.wav glunk

will cause one of "teleport/wav", "tele1/wav", "zap/wav" or "glunk" to be
played when something teleports.

NB: if the specified sound cannot be found then no sound is played.  No error
is reported.

It's also possible to specify "*" as a sound name to mean "no new sound".
This can be useful since it won't stop any previous sound playing, eg.

   hit = * * * * * splat.wav

would give a 1 in 6 chance of playing "splat.wav" when hitting monsters.



Sound files
```````````
!AngSound is supplied with some sample WAV (RIFF Wave) files (and a default
configuration that will use them :)

You don't have to stick to WAV files though.  The PlayIt player that the
games use is very flexible and will handle a variety of sample formats
(see its documentation for more information).

The PlayIt module (and documentation, etc) is located in !AngSound.PlayIt



Hints and tips
``````````````
There's no real limit on the size (or length) of samples you use.  If
the game wants to play another sample then it will stop the current one
(if any) playing and start the new one.

Because the samples are loaded from disc as and when required you may find
the level of disc activity annoying (I know that I do).  A 'quick fix' is
to copy !AngSound into a RAM disc and double-click on it there (so that
the new location is noticed).  You can do this at any time, by the way,
even if a game is already playing samples from disc.  Of course, this
is only really useful if you have enough memory to spare for the RAM disc.

The hit and miss (and kill/flee, to a lesser extent) samples soon become
annoying.  Don't feel that because you /can/ have a sample for those events
that you /have/ to :)


Licence/Disclaimer/Credits and Contact details
```````````````````````````````````````````````
NB: Please also see the PlayIt documentation for its Licence, etc.

This software is supplied in good faith, but without any warranty of any
kind.  The author can not and will not be held responsible for any loss
or damage occurring due to the use, misuse or inability to use this
software.

If you are having problems, however, I'll be glad to try to help.

My apologies to Toby Haynes for the horrible things I did to his lovely
Angband icon in order to create the !AngSound one.

Contact details:

e-mail:
   mailto:musus@argonet.co.uk

WWW:
   http://www.argonet.co.uk/users/musus/ (my homepage)
   http://www.argonet.co.uk/users/musus/angband/ (my Angband port homepage)

Snail:
   Adny H, c/o 23 Baronsway, Whitkirk, Leeds, LS15 7AW, ENGLAND.

